Creating your own bulb files requires that you know how to use a resource-editing program, such as ResEdit or Resorcerer. It also requires that you have some art you’d like to use as a bulb.
Background Terminology
• A complete collection of bulbs is called a set. A set is what the user sees in the Bulb Factory. A set is stored as a 'Bulb' resource in your bulb file. A single bulb file may contain more than one 'Bulb' resource (and hence more than one set).
• When the user views a set in the bulb list, she sees a 32 x 32 preview icon and a text description. The text description contains the set’s name, the set’s description, your name, copyright information, and your address.
• A set has four different sides — you’ll generally (but not always) want to customize your bulbs so that the right side looks different from the left side, for example. Most of our bulb sets do this, but not all: “Have a Nice Day” doesn’t. A set also can optionally contain special icons for the corners; if you don’t provide special corner icons, Holiday Lights just uses one of the bulbs from the top or bottom.
• A side may include from one to eight flavors of bulb. For example, “Standard Lights” includes five different flavors, each of which is a different color. The “Jolly Holly” set includes three flavors, each of which is a different shape (for variety’s sake). Each side must have the same number of flavors.
Each flavor may be a different size, and there’s no size limit on bulb icons (although you’ll want to use some restraint if you’re planning to give them to others: a bulb that’s 64 x 64 pixels uses up four times as much memory as a 32 x 32 bulb).
• Each flavor may have from one to eight frames. A frame is a certain flash state of a bulb; when Holiday Lights “flashes” a bulb, it really just switches to the next frame. For example, “Standard Lights” has two frames (bright and dark); “Jolly Holly” only has one frame, and “Have a Nice Day” uses four frames (normal, normal, smiling, and grinning).
There are a number of restrictions on frames. First of all, each frame of a given flavor must have the same icon mask. Secondly, the number of frames must be either 1, 2, 4, or 8; you can’t have 3, 5, 6, or 7 frames. Finally, every flavor of a set must have the same number of frames: you can’t have one flavor with two frames and another with four.
So: a bulb set is made up of four sides of 1-8 flavors, each of which has 1-8 frames. Each of the four corners also can display 1-8 frames.
One final note: if you only have one frame, Holiday Lights provides a way to make that frame flash on and off, either alternating between light and dark, or by applying the user’s “Label” menu colors to it. More info about this below.
Tutorial
Now, let’s apply what we know and make a set of bulbs. (You can follow along with this example by opening the file called “Bulb Example” in this folder; it’s a simplified version of the “Chili Peppers” bulb set that comes with Holiday Lights.)
First of all, create 'cicn' resources in ResEdit or Resorcerer. You can also use 'icl8' resources, but we recommend against it because you can’t modify the size, you have to include 'ICN#' resources for the mask, and they take up more space on the disk. Assume the icons look like this:
We want to make the chili peppers flash on and off by alternating the light and dark frames. In addition, we’re going to be clever: we’d like the bulbs to flash on and off in an alternating pattern, so that half are on and half are off at any given time.
We need to decide a few things:
• Do we have different icons for each side? In this example, we do.
• Do we have custom corner icons? In this case, no.
• How many flavors are there on each side? In this case, we have two flavors: one of them starts out bright and gets dark, and the other one starts out dark and gets bright. But we’re going to be clever, as I said, which means we’re going to use the same icons for the two flavors — which brings up an important point: multiple flavors or frames can share the same icons if appropriate. You’ll see how it’s done in a moment.
• How many frames are in each flavor, and what order do they appear in? We have two here: the first flavor of the top side consists of icons 1000 (first frame) and 1100 (second frame). The second flavor will use 1100 and 1000 (again, two frames, but the icons are in a different order).
Now that we know this information, we can create the 'Bulb' resource. You’ll find a ResEdit/Resorcerer template for this file in the “Bulb Example” file; copy this to any other file you create so that the 'Bulb' resource is easy to edit. Create a new bulb resource (it can have any resource ID or name). You’ll see a window that looks like this (these examples are in ResEdit, but the same instructions apply to Resorcerer).
We’ll first want to fill out some basic information. Set the version to 1 (future versions of Holiday Lights may use a different 'Bulb' format, so this is important). Then fill in the number of flavors and frames (2 of each in our example).
The next two buttons (AutoDim Flashing and AutoLabel Flashing) control whether you want Holiday Lights to automatically flash your bulbs by dimming them or by applying label colors to them. You can only turn on one of these. Since we’re using art that already contains frames that handle the flashing, we’ll turn them both off.
The next space (Description ID) is the resource ID of a 'STR#' resource that contains description information; take a look at the Bulb Example 'STR#' to see what goes where. We’ll put 128 in this space, since that’s the ID of our 'STR#'.
The next space (Preview ID) is the resource ID of the 32 x 32 pixel icon that the user sees in the bulb list of the Bulb Factory. Icon ID 1000 seems like a nice one to use for this. The first few fields now look like this:
After this, there’s a whole bunch of fields that allow you to enter the resource IDs for each of the frames of the corner bulbs; we’ll ignore them for this example, because we’re not using custom corner icons. Leave them blank or set them to 0. (If you want to use corner icons in your own bulbs, read through the technique described below for specifying flavors, and then just fill in the corner information as though it were a flavor).
Down at the bottom, you’ll see “Flavors 0”:
But we need two flavors, so we need to change it to “Flavors 2” — do this by clicking on the **** and choosing “Insert New Field(s)” from the Resource menu twice. You’ll now have something looking like this:
“Flavors 2” simply shows us that there is space for two flavors below the list. What we’re editing is simply a list of resource IDs for each frame of each side of each flavor. “1) ****” means that this is the first flavor. We just need to fill it in, leaving unused frames blank. So: the two frames of the top side of the first flavor are icon resources 1000 and 1100, in that order. Go ahead and type them in. Below that, you’ll see spaces for the right, bottom, and left sides. Fill them all in; the first part will look like this:
Scroll down a little further, and you’ll see “2) ****” — this is the list of frames for the second flavor. Remember that this flavor uses the same icons, but in a different order:
When you get to the bottom of this list — you’re done! Edit the description 'STR#' resource to contain the name of the bulb set, etc., save the file, and put it in your “Bulb Files” folder. If for some reason it doesn’t work, you can open it up and compare it with the “Finished Bulb Example” file to see where you went wrong — that file is a finished, working version.
Final Notes
A couple of other small details: if you want your file to have the nifty Holiday Lights bulb icon, you should change its creator and type codes to “110V” and “Bulb”, respectively (choose “Get Info for Bulb Example” from ResEdit’s File menu).
Don’t add your bulbs to the Holiday Lights application. Instead, create new files (you can duplicate the “Bulb Example”) and add them to your “Bulb Files” folder.
Finally, if you create any cool bulbs that you’d like to share with other people, please spread them around: upload them to your favorite online service, and send them to us. We’ll put them on our World Wide Web site. Thanks for helping us spread some Holiday cheer around!
